APPENDIX A: SOURCE CODE LISTINGS 
Copyright © 2001 LightSurf Technologies, Inc. 



48 



/* 

The AbstractCommandTag class, which demonstrates: 

1. Conditional execution of the execute () method based on HTTP request 
method (GET, POST, or the like) . 

2. Conditional execution of the execute () method based on the value of the 
HTTP request parameter named "key" . If this request parameter matches the 
descendant tag's attribute named "key", the execute () method is run. 

3. Page routing based on the success or failure of the execute () method. 
If the execute () method does not throw an exception, it has succeeded. If 
the execute ( ) method succeeds, the request is routed to the page specified 
in the tag's "onSuccess" attribute, if present. If the executef) method 
fails, the request is routed to the page specified in the tag's "onFailure" 
attribute, if present. An additional tag attribute named "redirect" 
controls whether this routing is performed inside the servlet engine 
(redirect= 1 false ' ) or through an HTTP redirect return code 

(redirect= 1 true ' ) . 

4. Utility method which descendant classes can use to check for required 
HTTP request parameters in a standard manner. 

5. Utility method which can populate a JavaBean with the values contained 
in an HTTP request. 

6. Utility method which can set arbitrary properties in a JavaBean. 
*/ 

package com. lightsurf . taglib; 

import j avax . servlet . * ; 
import j avax. servlet . http. * ; 
import j avax. servlet . jsp. * ; 

import j avax . servl et . j sp . t agext . TagSupport ; 

import j ava . beans . * ; 

import j ava . lang. reflect . * ; 

import j ava .util . Enumeration; 

import j ava . io . IOExcept ion ; 

import java . io . PrintWriter ; 
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import j ava . text . * ; 
import java.util , * ; 

import com. light surf .util. *; 

* AbstractCommandTag is the base class for all 

* command tags in the tag library framework. This 

* tag provides the following services: 

* <ul> 

* <li>filter command by HTTP request method 

* <li>filter command by request parameter <code>key</code> 

* <li>redirect request on command success or failure using 

* either JSP forward or HTTP redirect 

* <li>set bean properties from request parameters using 

* introspection 

* </ul> 

* Descendant classes implement the <code>execute ( ) </code> 

* method. The class specifically does not have non-final 

* static members to increase its extensibility. 

* 

* ^author Paul Egli 

* Aversion 1.0 
*/ 

public abstract class AbstractCommandTag extends TagSupport { 

private static final int ABSTRACTC OMMANDT AG_START = 9600; 
private static final int SERVLETEXCEPTION = 9600; 
private static final int BEAN„ERROR = 9601; 

public static String className = AbstractCommandTag. class . getName { ) 

public static final String KEY_PARAMETER = "key 11 ; 
public static final String PAGE_PARAMETER = "page"; 
public static final String METHOD__ANY = "any"; 

private String method = METHOD_ANY; 
private String key = null; 
private String onSuccess = null; 
private String onFailure = null; 
private boolean redirect = false; 

static{ 

LogCodes . checkLogCode (className , ABSTRACTCOMMANDTAG_START, 

LogCodes.TAGLIB_ABSTRACTCOMMANDTAG) ; 

} 

/ * * 

* Conditionally execute the command on GET, POST, or 

* ANY (default) HTTP method. 

* ©attribute method 

* @param method GET, POST, HEAD, etc., or ANY for any method 
*/ 

public final void setMethod (String method) { 
this. method = method; 

} 



50 



I * * 

* Getter for tag attribute <code>method</code> 

* ©return HTTP method to filter command on or ANY for no filtering 
*/ 

public final String getMethod ( ) { 
return method; 

} 

j * * 

* Optional command tag filter. The command tag will 

* not execute if the request parameter named "key" 

* is missing or its value does not match the value 

* of this attribute. 

* ©attribute key 

* ©param key arbitrary string that must match the value of the 

* request parameter named "key" . 
*/ 

public final void setKey (String key) { 
this. key = key; 

} 

/ * * 

* Getter for the tag attribute <code>key</code> 

* ©return Arbitrary string set in the tag attribute as a 

* request filter. 
*/ 

public final String getKeyO { 
return key; 

} 

/ * * 

* Route to this URI on command success. 

* ©attribute onSuccess 

* ©param onSuccess String containing an absolute or relative URL to 

* redirect or forward the request to if the 

* <code>execute ( ) </code> method does not throw an 

* exception or throw an exception to the page 
eption 

* stack. 
*/ 

public final void setOnSuccess (String onSuccess) { 
this . onSuccess = onSuccess; 

} 

I * * 

* Getter for the tag attribute <code>onSuccess</code> . 

* ©return String containing a URL to forward or redirect to 

* if the <code>execute ( ) </code> method succeeds. 
*/ 

public final String getOnSuccess { ) { 
return onSuccess; 

} 
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I * * 

* Route to this URI on command failure 

* ©attribute onFailure 

* ©param onFailure String containing an absolute or relative URL to 

* redirect or forward the request to if the 

* <code>execute ( ) </code> method throws an 

* exception or puts an exception to the page 
exception 

* stack. 
*/ 

public final void setOnFailure (String onFailure) { 
this . onFailure = onFailure; 

} 

I * * 

* Getter for the tag attribute <code>onFailure</code> . 

* ©return String containing a URL to forward or redirect to 

* if the <code>execute { ) </code> method fails. 
*/ 

public final String getOnFailure { ) { 
return onFailure; 

} 

J -k * 

* If true, issue an HTTP 3 02 Redirect for onSuccess 

* or onFailure. If false, use JSP forward. Default 

* value is false for redirect. 
* 

* ©attribute redirect 

* ©param redirect if true, use HTTP redirect, if false, use JSP 
forwarding 

*/ 

public final void setRedirect {boolean redirect) { 
this . redirect = redirect; 

} 

I * * 
* 

* ©return True if using HTTP redirect, false if using JSP forwarding. 

* Default value is false for redirect. 
*/ 

public final boolean getRedirect ( ) { 
return redirect; 

} 



/ * * 

* Main method that is overridden in descendant classes. 

* Any exceptions thrown by this method are caught and 

* added to the page exception queue. 

* ©param request Incoming servlet request. HttpServletRequest is used 

* so the command tag has access to the HTTP request 

* method (GET, POST, etc) for selective execution. 

* ©exception CommandTagException 

* Any runtime exceptions should be wrapped into 
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* ComrnandTagException so they can be stored in the 

* page exception stack. 
*/ 

protected abstract void execute (PageContext pageContext) throws 
ComrnandTagException ; 

protected abstract boolean verify {PageContext pageContext) throws 
JspTagExcept ion ; 

I * * 

* Calls the execute ( ) method if the request method 

* is correct and the optional key parameter is 

* present in the request. Puts CommandTagExceptions into the 

* exception queue for later retreival . 

* ^return 

* ^exception JspException 
*/ 

public int doStartTagO throws JspException { 

HttpServletRequest request = (HttpServletRequest ) 
pageContext . getRequest { ) ; 

// IF there are errors then dont run any of the commands on this 

page. 

if (TagFrameworkSupport .haveExceptionErrors (pageContext ) ) { 
return SKIP_BODY; 

} 

// skip the execution if the key tag is missing 
if (key != null 

! key. equalsIgnoreCase (KeyUtil . decodeForm (request . getParameter ( KEY_PARAMETER 
)))) { 

return SKIP_BODY; 

} 

// skip the command if the request method is not "any" or doesn't 
matche the method parameter 

if { ! method. equalsIgnoreCase (METHOD_ANY) 
! method . equalsIgnoreCase ( request . getMethod ( ) ) } { 

return SKIP_BODY; 

} 

if (verify (pageContext ) ) { 

// perform form submission only if form validates successfully 

try { 

execute {pageContext ) ; 

1 

catch (ComrnandTagException e) { 

// something dreadful happened. throw an exception to the 

page 

throw new JspTagExcept ion (e . getMessage ( ) ) ; 

} 

} 

if (TagFrameworkSupport .haveExceptionErrors (pageContext) ) { 

// redirect the page on success if the next attribute is set 
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if (onFailure null) { 

HttpServletResponse response = (HttpServletResponse) 
pageContext . getResponse ( ) ; 

if (redirect) { 

try { 

response . sendRedirect (response. encodeRedirectURL (onFailure) ) ; 

} 

catch (lOException e) { 

throw new JspTagException (" lOException while trying 
to sendRedirect ( "+onFailure+" ) in AbstractCommandTag. doS tar tTag() " ) ; 

} 

} 

else { 

try { 

RequestDispatcher rd = 
pageContext . getServletContext ( ) . getRequestDispatcher (response . encodeURL (onF 
ailure) ) ; 

rd . forward (pageContext . getReques t { ) , 
pageContext . getResponse ( ) ) ; 

} 

catch (lOException e) { 

throw new JspTagException (" lOException while trying 
to forward { "+onFailure+ 11 ) in AbstractCommandTag" ) ; 

} 

catch (ServletException e) { 

throw new JspTagException ( "ServletException while 
trying to forward ( "+onFailure+" ) in AbstractCommandTag"); 

} 

} 

} 

} 

// redirect the page on success if the next attribute is set 
else if (onSuccess != null) { 

HttpServletResponse response = (HttpServletResponse) 
pageContext . getResponse ( ) ; 

if (redirect) { 
try { 

response. sendRedirect (response . encodeRedirectURL (onSuccess) ) ; 

} 

catch (lOException e) { 

throw new JspTagException (" lOException while trying to 
sendRedirect ( " +onSuccess+ " ) in AbstractCommandTag . doStartTag ( ) " ) ; 

} 

} 

else { 

try { 

RequestDispatcher rd = 
pageContext . getServletContext ( ) . getRequestDispatcher (response . encodeURL (onS 
nccess) ) ; 

rd . forward (pageContext . getReques t ( ) , 
pageContext . getResponse ( ) ) ; 

} 

catch (lOException e) { 

throw new JspTagException { "lOException while trying to 
forward ( " +onSuccess+ " ) in AbstractCommandTag" ) ; 
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} 

catch (ServletException e) { 

Log . printError ( className , SERVLETEXCEPTION, 

"ServletException while trying to 

forward (" + onSuccess + " ) " , 

(Throwable) e) ; 
throw new JspTagException ( "ServletException while 
trying to forward ( " +onSuccess+ " ) in AbstractCommandTag" } ; 

} 

} 

} 

return SKIP_BODY; 

} 



I -k-k 

* Utility method which throws a populated MissingParameterException 

* if any of the properties named in requiredParams 

* are missing from the servlet request 

* @param request 

* @param requiredParams 

* ^exception MissingParameterException 

*/ 

protected void checkForRequiredParameters (PageContext pageContext, 
String [] requiredParams) throws MissingParameterException { 

if (requiredParams — null) { 
return; 

} 

ServletRequest request = pageContext . getRequest () ; 

boolean [] flags = new boolean [requiredParams . length] ; 
for (int i=0; i < flags . length; i++) { 
flags [i] = false; 

} 

for (int i=0; i < requiredParams . length; i++) { 
String param = requiredParams [i] ; 
String subparam = requiredParams [i] ; 
boolean multiple = false; 
if ( par am. ends Wi thC**" ) ) { 

subparam = param. substring { 0 / subparam. length ( ) -1 ) ; 
multiple = true; 

} 

for ( java .util . Enumeration e = request .getParameterNames () ; 
e .hasMoreElements ( ) ; ) { 

String name = (String) e .next Element () ; 
if (multiple) { 

flags [i] = name . start sWith (subparam) && 
(request . getParameter (name) . length ( ) > 0) ; 

} 

else { 

flags [i] = name . equals (param) 
(request . getParameter (name) . length ( ) > 0); 

} 
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if (flags [i]) { 
break; 

} 

} 

} 

// construct MPEs and put into page 
for (int i=0; i < flags . length; i++) { 
if (! flags [i]) { 

TagFrameworkSupport . throwToPage (pageContext , new 
Mi ssingParameterExcept ion ( "Required parameter " + requiredParams [i] + " 
missing" , requiredParams [i] ) ) ; 

} 

} 



I * * 

* Convenience method to set all bean properties from 

* request parameters . Request parameters that do 

* not map to bean properties are ignored. 

* <p> 

* <b>Important notei</b> Call this method with the 

* highest base class of the bean possible. For example, 

* if a class or interface named Album extends a class 

* or interface named Container, call this method with 

* Container, class, not Album. class. If you use Album, class, 

* this method will only set the object properties in 

* the Album class and will not look up to the parent 

* class for properties. 

* @param els Class of the bean whose parameters are being set 

* @param bean The JavaBean whose parameters are being set. 

* ©param request The request containing parameters 

* ©exception CommandTagException 

* Thrown if any introspection errors occur 
*/ 

public static void setBeanProperties (Class els/ Object bean, 
ServletRequest request) throws CommandTagException { 
String propertyName = null; 

try { 

Beanlnfo beanlnfo = Introspector . getBeanlnf o (els) ; 
PropertyDescriptor [ ] descriptors = 
beanlnfo . getPropertyDescriptors ( ) ; 

for {Enumeration e = request . get ParameterNames () ; 
e . hasMoreElements ( ) ; ) { 

propertyName = (String) e .next Element () ; 
Method setter = null; 

for (int i=0; i < descriptors . length; i++) { 

PropertyDescriptor descriptor = descriptors [i] ; 
if (descriptor . getName (). equals (propertyName) ) { 
setter = descriptor . getWriteMethod () ; 
if (setter != null) { 
try { 

setter . invoke (bean, 
coerceReques tParamet erValue ( setter , request . get Parameter (propertyName ) ) ) 
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} 

catch (Illegal Argument Except ion ex) { 

Log. printError (className, BEAN_ERROR, 

"Could not set 

property ' " + propertyName + " 1 of bean ' " + 

els . getName ( ) + 1,1 

to ' " + request . get Parameter (propertyName) + 

H . If t 

» ' 

ex . getMessage { ) ) ; 

} 

} 

// ignore read-only properties that were specified 
break; 

} 



in the request 



} 

> 

} 

catch ( Introspect ionException e) { 

throw new CommandTagException (e .getMessage { ) ) ; 

} 

catch (InvocationTargetException e) { 

throw new CommandTagException ( "Unable to access property 
1 " +propertyName+" ' of bean ' "+cls .getName ( ) + 11 ' in AbstractCommandTag" ) ; 
} 

catch (IllegalAccessException e) { 

throw new CommandTagException ( "Unable to access property 
' "+propertyName+" 1 of bean ' 11 +cls . getName ()+" 1 in AbstractCommandTag"); 
} 

} 

/ * * 

* This routine is 

* used inside the <code>setBeanProperty ( ) </code> and 

* <code>setBeanProperties ( ) </code> methods to 

* automagically convert a String into the appropriate 

* type for an Introspection method call. 

* ©param setmethod The method passed in is examined for property type 

* ©param value The value to be converted to the appropriate type 
for the method passed in. 

* ©return an Object array containing the appropriate 

* object type for a given method. 

* ©exception II legal Argument Except ion 
*/ 

private static Object [] coerceRequestParameterValue (Method setmethod, 
String value) throws IllegalArgumentException { 

Class [] types = setmethod. getParameterTypes () ; 
if (types 1= null && types. length ==1) { 
if (types [0] == Boolean . TYPE) { 

return new Object [] { new Boolean (value) } ; 

} 

else if {types [0] == Character .TYPE) { 
if (value J= null) { 

return new Object [] { new Character (value . charAt (0) )} ; 

} 

} 

else if (types [0] == Byte. TYPE) { 
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return new Object [] { new Byte (value) } ; 

} 

else if (types [0] == Short. TYPE) { 

return new Object [] { new Short (value) } ; 

5 } 

else if (types [0] == Integer . TYPE) { 

return new Object [] { new Integer (value) } ; 

} 

else if (types [0] == Long. TYPE) { 
10 return new Object [] { new Long (value) } ; 

} 

else if (types [0] == Float. TYPE) { 

return new Object [] { new Float (value) } ; 

} 

15 else if (types [0] == Double. TYPE) { 

return new Object [] { new Double (value) } ; 

} 

else if (types [0] ~- Date. class || types[0] == 
java . sql . Date . class ) { 
20 try { 

return new Ob j ect [ ] { 
TagFrameworkSupport . DATE_FORMAT. parse (value) } ; 

} 

p catch ( java . text . Pars eExcept ion e) { 

throw new IllegalArgumentException ( e . getMessage ( ) ) ; 

} 

} 

} 

return new Object[] { value}; // default action 

} 

f-k* 

* Uses introspection to set a single property in a bean 

* @param els The class of the bean to be read 

01 * @pararn bean The object in which to set the property 

M: * @param propertyName 

in * the name of the property to read 

* ©param proper tyValue 

r^fO * The value of the property as a String 

p " : * ©exception JspTagException 

* Thrown if the named property isn't present in the 

* bean. Additionally, any problems with 
introspection 

45 * are wrapped in a JspTagException 

*/ 

public static void setBeanProperty (Class els, Object bean, String 
propertyName/ String proper tyValue) throws JspTagException { 
try { 

50 Beanlnfo beanlnfo = Introspector . getBeanlnf o (els) ; 

PropertyDescriptor [ ] descriptors = 
beanlnfo . getPropertyDescriptors ( ) ; 

Method setter = null; 

for (int i=0; i < descriptors . length; i++) { 
55 PropertyDescriptor descriptor = descriptors [i 3 ; 

if (descriptor . getName ( ) . equals (propertyName) ) { 
setter = descriptor . getWriteMethod ( ) ; 
break; 

58 



} 

} 

if (setter == null) { 

throw new JspTagException (els . getName ( ) + 11 does not have 
property named r " +propertyName+ " ' " ) ; 

} 

Object result = setter . invoke (bean, 
coerceRequestParameterValue (setter, proper tyValue) } ; 

} 

catch ( IntrospectionException e) { 

throw new JspTagException (e . getMessage ( ) ) ; 

} 

catch (InvocationTargetException e) { 

throw new JspTagException { "Unable to access property 
■ " +propertyName+ " ' of bean ' 11 +cls , getName ( ) + " ' in AbstractCommandTag" ) / 
} 

catch (IllegalAccessException e) { 

throw new JspTagException ( "Unable to access property 
' " +propertyName+ " 1 of bean ' "+C1S .getName {)+" 1 in AbstractCommandTag"); 
} 

} 

} 
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/* 

TagFrameworkSupportExample . java contains methods which are called to store 
and retrieve recoverable errors that may occur during the execution of 
AbstractCommandTag descendant classes. 
*/ 

J * * 

* Class for static utility methods used 

* in the tag library framework. 

* Methods which support error recording from AbstractCommandTag are 

* implemented in this class. 

*/ 

public abstract class TagFrameworkSupport { 



/ * * 

* Adds an exception to the exception hold. This method 

* is used to stack up exceptions for later processing 

* instead of throwing exceptions to the servlet 

2 0 * container. Descendants of AbstractCommandTag can use 

* this method to indicate that a recoverable exception 

* has occurred during processing of their execute () 

* methods . 



* @param pageContext 

rfk * @param exception 

Tz public static void throwToPage (PageContext pageContext, 

H:;- CommandTagException exception) { 

ISO if (pageContext == null) { 

Hj return; 

in } 



Servlet Request request = pageContext . getRequest () ; 



tcH Vector exceptionHold = (Vector) 

H : request . getAttribute (TagConstants . EXCEPT I ON_HOLD_NAME ) ; 

yi if (exceptionHold == null) { 

exceptionHold = new Vector (0, 1); 
ff 0 request . setAttribute (TagConstants . EXCEPT I 0N_H0LD_NAME , 

" : exceptionHold) ; 

} 



exceptionHold. a ddElement (exception) ; 



/ * * 

* Examines the page exception stack and returns an 

* array of exceptions which match the class type 
50 * passed in, 

* @param pageContext 

* JSP page context used to retrieve the exception stack 

* @param type name of the exception class to retrieve. 

55 * ©return an array of CommandTagExceptions . Will return a zero- 

* length array if no exceptions in the stack matched the 

* given type or if the type parameter is null. 

* ©exception JspException 
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*/ 

public static CommandTagException [ ] getExceptionsByType (PageContext 
pageContext, String type) throws JspException { 
if (type == null) { 

return new CommandTagException [0] ; 

} 

try { 

Class els = Class . forName (type) ; 

return getExceptionsByClass (pageContext , els); 

} 

catch (ClassNotFoundException e) { 

throw new JspException ( "Could not load class " +type+" in 
TagSupportFramework. getExceptionsByType ( ) " ) ; 
} 

} 

j * * 

* Examines the page exception stack and returns an 

* array of exceptions which match the class passed in. 

* ©param pageContext 

* JSP page context used to retrieve the exception sta 

* ©param els The class of exception to search for in the 

* exception stack 

* ©return an array of CommandTagExceptions . Will return a zero- 

* length array if no exceptions in the stack matched the 

* given class or if the class parameter is null. 

* ©exception JspException 

*/ 

public static CommandTagException [ ] getExceptionsByClass (PageContext 
pageContext, Class els) { 

Vector exceptionHold = (Vector) 
pageContext . getRequest ( ) . getAttribute (TagConstants . EXCEPTION_HOLD_NAME) ; 
if (exceptionHold == null) { 

return new CommandTagException [ 0 ] ; 

} 

Vector matches = new Vector (0, 1) ; 
for (Enumeration e = exceptionHold. elements () ; 
e . hasMoreElements { ) ; ) { 

Object o = e .nextElement ( ) ; 
if {els . islnstance (o) ) { 
matches . addElement (o) ; 

} 

} 

CommandTagException!] result = new 
CommandTagException [matches . size ( ) ] ; 
matches . copylnto (result) ; 
return result; 

} 

I * * 

* Find out how many exceptions are currently stored 

* in the page exception stack 

* ©param pageContext 

* JSP page context object used to retrieve the stack 

* ©return the size of the page exception stack 
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*/ 

public static int getExceptionCount {PageContext pageContext ) { 
Vector except ionHold = (Vector) 
pageContext . getReguest ( ) . getAttribute {TagConstants . EXCEPT I ON__HOLD_NAME ) ; 
if { except ionHold— null) 

return 0; 
return except ionHold. size () ; 



I * * 

* If the exception hold contains any exceptions, 

* return true, otherwise return false. 

* @param pageContext 

* ©return 
*/ 

public static boolean haveExceptionErrors {PageContext pageContext) { 
CommandTagExcept i on [ ] exceptions = 
getExceptionsByClass (pageContext , SuccessExcept ion . class) ; 

if (getExceptionCount (pageContext ) > exceptions . length) { 
return true; 

} 

return false; 



} 
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/* 

CommandTagExample . java is an example of how to write a simple command 
tag class which extends AbstractCommandTag. By virtue of extending 
AbstractCommandTag, CommandTagExample can do page routing and error 
handling, as illustrated in the source code. 
*/ 



import j ava . io . * ; 

public class CommandTagExample extends AbstractCommandTag { 



I * * 

* This command tag opens a server-side file and writes 
15 * the text "hello, world!". 

* @param pageContext 

* ©exception CommandTagException 
*/ 

2 0 protected void execute (PageContext pageContext) throws 

C ommandTagExc ep t i on { 

try { 

File logfile = new File ( " /var/tmp/ example . log" ) ; 

3 FileWriter writer = new FileWriter ( logfile) ; 
35 writer .write ( "hello, world!"); 
~I writer . close () ; 

m catch (FileNotFoundException e) { 

f II / * * 

ISO * For example purposes, this error is determined to be 

f%\ recoverable, 

zk * so the error is added to the list of recoverable errors for 

v ' the 

L_ * current page. The AbstractCommandTag will now route the 

Ml 5 user based 

CP * based on the onFailure tag attribute. 

y, * / 

\ f\ TagFrameworkSupport . throwToPage (pageContext , new 

2- CommandTagException ( "Could not find example log file' 1 )); 

Ho } 

catch (IOException e) { 

j * * 

* For example purposes, this error is determined to be 

critical, so 

45 * when it occurs, page execution should stop. This is 

indicated by 

* actually throwing a Java exception rather than calling the 

throwToPage ( ) 

* method in TagFrameworkSupport . 
50 */ 

throw new CommandTagException { "Error writing to the example log 

file! rr ) ; 

} 

} 

55 } 
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